/*
 * Copyright 2008 Bulent Kucuk, Inc. All rights reserved.
 * Use is subject to license terms.
 */

package sopa.java.documentation;

import java.math.BigDecimal;
import java.math.RoundingMode;

/**
 * Immutable arbitrary-precision integers. All operations behave as if
 * BigIntegers were represented in two's-complement notation (like Java's
 * primitive integer types).
 * <p>
 * Semantics of arithmetic operations exactly mimic those of Java's integer
 * arithmetic operators, as defined in <i>The Java Language Specification</i>.
 * <p>
 * All methods and constructors in this class throw
 * <CODE>NullPointerException</CODE> when passed a null object reference for any
 * input parameter.
 * 
 * @see OtherClass
 * @version 1.5
 * @author Bulent Kucuk
 */
public class DocumentedClass
{
    /**
     * The scale of this BigDecimal, as returned by {@link #scale}.
     * 
     * @serial
     * @see #scale
     */
    @SuppressWarnings("unused")
    private final int scale = 0; // Note: this may have any value.

    /**
     * The signum of this BigInteger: -1 for negative, 0 for zero, or 1 for
     * positive. Note that the BigInteger zero <i>must</i> have a signum of 0.
     * This is necessary to ensures that there is exactly one representation for
     * each BigInteger value.
     */
    int signum;

    /**
     * Sentinel value for {@link #intCompact} indicating the significand
     * information is only available from {@code intVal}.
     */
    private static final long INFLATED = Long.MIN_VALUE;

    /**
     * If the absolute value of the significand of this BigDecimal is less than
     * or equal to {@code Long.MAX_VALUE}, the value can be compactly stored in
     * this field and used in computations.
     */
    @SuppressWarnings("unused")
    private transient final long intCompact = INFLATED;

    // All 18-digit base ten strings fit into a long; not all 19-digit
    // strings will
    @SuppressWarnings("unused")
    private static final int MAX_COMPACT_DIGITS = 18;

    /**
     * Translates a character array representation of a <tt>BigDecimal</tt> into
     * a <tt>BigDecimal</tt>, accepting the same sequence of characters as the
     * {@link #BigDecimal(String)} constructor, while allowing a sub-array to be
     * specified and with rounding according to the context settings.
     * 
     * @param in
     *            <tt>char</tt> array that is the source of characters.
     * @param offset
     *            first character in the array to inspect.
     * @param len
     *            number of characters to consider..
     * @param mc
     *            the context to use.
     * @throws ArithmeticException
     *             if the result is inexact but the rounding mode is
     *             <tt>UNNECESSARY</tt>.
     * @throws NumberFormatException
     *             if <tt>in</tt> is not a valid representation of a
     *             <tt>BigDecimal</tt> or the defined subarray is not wholly
     *             within <tt>in</tt>.
     * @since 1.5
     */
    public DocumentedClass(char[] in, int offset, int len, int mc)
    {
        // ...
    }

/**
     * Translates the string representation of a <tt>BigDecimal</tt>
     * into a <tt>BigDecimal</tt>.  The string representation consists
     * of an optional sign, <tt>'+'</tt> (<tt>'&#92;u002B'</tt>) or
     * <tt>'-'</tt> (<tt>'&#92;u002D'</tt>), followed by a sequence of
     * zero or more decimal digits ("the integer"), optionally
     * followed by a fraction, optionally followed by an exponent.
     * 
     * <p>The fraction consists of a decimal point followed by zero
     * or more decimal digits.  The string must contain at least one
     * digit in either the integer or the fraction.  The number formed
     * by the sign, the integer and the fraction is referred to as the
     * <i>significand</i>.
     *
     * <p>The exponent consists of the character <tt>'e'</tt>
     * (<tt>'&#92;u0065'</tt>) or <tt>'E'</tt> (<tt>'&#92;u0045'</tt>)
     * followed by one or more decimal digits.  The value of the
     * exponent must lie between -{@link Integer#MAX_VALUE} ({@link
     * Integer#MIN_VALUE}+1) and {@link Integer#MAX_VALUE}, inclusive.
     *
     * <p>More formally, the strings this constructor accepts are
     * described by the following grammar:
     * <blockquote>
     * <dl>
     * <dt><i>BigDecimalString:</i>
     * <dd><i>Sign<sub>opt</sub> Significand Exponent<sub>opt</sub></i>
     * <p>
     * <dt><i>Sign:</i>
     * <dd><tt>+</tt>
     * <dd><tt>-</tt>
     * <p>
     * <dt><i>Significand:</i>
     * <dd><i>IntegerPart</i> <tt>.</tt> <i>FractionPart<sub>opt</sub></i>
     * <dd><tt>.</tt> <i>FractionPart</i>
     * <dd><i>IntegerPart</i>
     * <p>
     * <dt><i>IntegerPart:
     * <dd>Digits</i>
     * <p>
     * <dt><i>FractionPart:
     * <dd>Digits</i>
     * <p>
     * <dt><i>Exponent:
     * <dd>ExponentIndicator SignedInteger</i>
     * <p>
     * <dt><i>ExponentIndicator:</i>
     * <dd><tt>e</tt>
     * <dd><tt>E</tt>
     * <p>
     * <dt><i>SignedInteger:
     * <dd>Sign<sub>opt</sub> Digits</i>
     * <p>
     * <dt><i>Digits:
     * <dd>Digit
     * <dd>Digits Digit</i>
     * <p>
     * <dt><i>Digit:</i>
     * <dd>any character for which {@link Character#isDigit}
     * returns <tt>true</tt>, including 0, 1, 2 ...
     * </dl>
     * </blockquote>
     *
     * <p>The scale of the returned <tt>BigDecimal</tt> will be the
     * number of digits in the fraction, or zero if the string
     * contains no decimal point, subject to adjustment for any
     * exponent; if the string contains an exponent, the exponent is
     * subtracted from the scale.  The value of the resulting scale
     * must lie between <tt>Integer.MIN_VALUE</tt> and
     * <tt>Integer.MAX_VALUE</tt>, inclusive.
     *
     * <p>The character-to-digit mapping is provided by {@link
     * java.lang.Character#digit} set to convert to radix 10.  The
     * String may not contain any extraneous characters (whitespace,
     * for example).
     *
     * <p><b>Examples:</b><br>
     * The value of the returned <tt>BigDecimal</tt> is equal to
     * <i>significand</i> &times; 10<sup>&nbsp;<i>exponent</i></sup>.  
     * For each string on the left, the resulting representation
     * [<tt>BigInteger</tt>, <tt>scale</tt>] is shown on the right.
     * <pre>
     * "0"            [0,0]
     * "0.00"         [0,2]
     * "123"          [123,0]
     * "-123"         [-123,0]
     * "1.23E3"       [123,-1]
     * "1.23E+3"      [123,-1]
     * "12.3E+7"      [123,-6]
     * "12.0"         [120,1]
     * "12.3"         [123,1]
     * "0.00123"      [123,5]
     * "-1.23E-12"    [-123,14]
     * "1234.5E-4"    [12345,5]
     * "0E+7"         [0,-7]
     * "-0"           [0,0]
     * </pre>
     *
     * <p>Note: For values other than <tt>float</tt> and
     * <tt>double</tt> NaN and &plusmn;Infinity, this constructor is
     * compatible with the values returned by {@link Float#toString}
     * and {@link Double#toString}.  This is generally the preferred
     * way to convert a <tt>float</tt> or <tt>double</tt> into a
     * BigDecimal, as it doesn't suffer from the unpredictability of
     * the {@link #BigDecimal(double)} constructor.
     *
     * @param val String representation of <tt>BigDecimal</tt>.
     *
     * @throws NumberFormatException if <tt>val</tt> is not a valid 
     *         representation of a <tt>BigDecimal</tt>.
     */
    public DocumentedClass(String val)
    {
        // ...
    }

/**
     * Returns a BigInteger whose value is <tt>(this % val)</tt>.
     * 
     * @param val
     *            value by which this BigInteger is to be divided, and the
     *            remainder computed.
     * @return <tt>this % val</tt>
     * @throws ArithmeticException
     *             if the result is inexact but the rounding mode is
     *             <tt>UNNECESSARY</tt>.
     */
    public int remainder(int val)
    {
        return 0;
    }

/**
     * Returns a <tt>BigDecimal</tt> whose value is <tt>(this /
     * divisor)</tt>, and whose scale is <tt>this.scale()</tt>.  If
     * rounding must be performed to generate a result with the given
     * scale, the specified rounding mode is applied.
     * 
     * <p>The new {@link #divide(BigDecimal, RoundingMode)} method
     * should be used in preference to this legacy method.
     * 
     * @param  divisor value by which this <tt>BigDecimal</tt> is to be divided.
     * @param  roundingMode rounding mode to apply.
     * @return <tt>this / divisor</tt>
     * @throws ArithmeticException if <tt>divisor==0</tt>, or
     *         <tt>roundingMode==ROUND_UNNECESSARY</tt> and
     *         <tt>this.scale()</tt> is insufficient to represent the result
     *         of the division exactly.
     * @throws IllegalArgumentException if <tt>roundingMode</tt> does not
     *         represent a valid rounding mode.
     * @see    #ROUND_UP
     * @see    #ROUND_DOWN
     * @author Someone Else
     */
    public int divide(int divisor, int roundingMode)
    {
        return 0;
    }

    /**
     * Entry point to the test application.
     * 
     * @param args
     *            array of string arguments
     */
    public static void main(String[] args)
    {
        System.out.println("Hello");
    }
}
